Skip Headers

Oracle® Data Provider for .NET Developer's Guide 10g Release 2 (10.2) Part Number B14307-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OracleBFile Class

An `OracleBFile` is an object that has a reference to `BFILE` data. It provides methods for performing operations on `BFILE`s.

Note: `OracleBFile` is supported for applications running against Oracle8.x and later.

Class Inheritance

`Object`

`MarshalByRefObject`

`Stream`

`OracleBFile`

Declaration

    // C#
    public sealed class OracleBFile : Stream, ICloneable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Remarks

`OracleBFile` is supported for applications running against Oracle8.x and later.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class OracleBFileSample
    {
            static void Main()
            {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Open the OracleBFile
        bFile.OpenFile();

        // Read 7 bytes into readBuffer, starting at buffer offset 0
        byte[] readBuffer = new byte[7];
        int bytesRead = bFile.Read(readBuffer, 0, 7);

        // Prints "bytesRead  = 7"
        Console.WriteLine("bytesRead  = " + bytesRead);

        // Prints "readBuffer = 65666768656667"
        Console.Write("readBuffer = ");
        for(int index = 0; index <  readBuffer.Length; index++)
        {
          Console.Write(readBuffer[index]);
        }
        Console.WriteLine();

        // Search for the 2nd occurrence of a byte pattern {66,67}
        // starting from byte offset 1 in the OracleBFile
        byte[] pattern = new byte[2] {66, 67};
        long posFound = bFile.Search(pattern, 1, 2);

        // Prints "posFound   = 6"
        Console.WriteLine("posFound   = " + posFound);

        // Close the OracleBFile
        bFile.CloseFile();

        bFile.Close();
        bFile.Dispose();

        con.Close();
        con.Dispose();
            }
    }

Requirements

Namespace: `Oracle.DataAccess.Types`

Assembly: `Oracle.DataAccess.dll`

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Members OracleBFile Constructors OracleBFile Static Fields OracleBFile Static Methods OracleBFile Instance Properties OracleBFile Instance Methods

## OracleBFile Members

`OracleBFile` members are listed in the following tables:

OracleBFile Constructors

`OracleBFile` constructors are listed in Table 10-1.

Table 10-1 OracleBFile Constructors

Constructor | Description
--- | ---
OracleBFile Constructors | Creates an instance of the `OracleBFile` class (Overloaded)

OracleBFile Static Fields

`OracleBFile` static fields are listed in Table 10-2.

Table 10-2 OracleBFile Static Fields

Field | Description
--- | ---
MaxSize | The static field holds the maximum number of bytes a `BFILE` can hold, which is 4,294,967,295 (2^32 - 1) bytes

OracleBFile Static Methods

`OracleBFile` static methods are listed in Table 10-3.

Table 10-3 OracleBFile Static Methods

Methods | Description
--- | ---
`Equals` | Inherited from `Object` (Overloaded)

OracleBFile Instance Properties

`OracleBFile` instance properties are listed in Table 10-4.

Table 10-4 OracleBFile Instance Properties

Properties | Description
--- | ---
CanRead | Indicates whether or not the LOB stream can be read
CanSeek | Indicates whether or not forward and backward seek operations can be performed
CanWrite | Indicates whether or not the LOB object supports writing
Connection | Indicates the connection used to read from a `BFILE`
DirectoryName | Indicates the directory alias of the `BFILE`
FileExists | Indicates whether or not the specified `BFILE` exists
FileName | Indicates the name of the `BFILE`
IsEmpty | Indicates whether the `BFILE` is empty or not
IsOpen | Indicates whether the `BFILE` has been opened by this instance or not
Length | Indicates the size of the `BFILE` data in bytes
Position | Indicates the current read position in the LOB stream
Value | Returns the data, starting from the first byte in `BFILE`, as a byte array

OracleBFile Instance Methods

`OracleBFile` instance methods are listed in Table 10-5.

Table 10-5 OracleBFile Instance Methods

Methods | Description
--- | ---
`BeginRead` | Inherited from `Stream`
`BeginWrite` | Not Supported
Clone | Creates a copy of an `OracleBFile` object
Close | Closes the current stream and releases any resources associated with the stream
CloseFile | Closes the `BFILE` referenced by the current `BFILE` instance
Compare | Compares data referenced by the two `OracleBFile`s
`CreateObjRef` | Inherited from `MarshalByRefObject`
CopyTo | Copies data as specified (Overloaded)
Dispose | Releases resources allocated by this object
`EndRead` | Inherited from `Stream`
`EndWrite` | Not Supported
`Equals` | Inherited from `Object` (Overloaded)
`Flush` | Not Supported
`GetHashCode` | Inherited from `Object`
`GetLifetimeService` | Inherited from `MarshalByRefObject`
`GetType` | Inherited from `Object`
`InitializeLifetimeService` | Inherited from `MarshalByRefObject`
IsEqual | Compares the LOB references
OpenFile | Opens the `BFILE` specified by the `FileName` and `DirectoryName`
Read | Reads a specified amount of bytes from the `OracleBFile` instance and populates the `buffer`
`ReadByte` | Inherited from `Stream`
Search | Searches for a binary pattern in the current instance of an `OracleBFile`
Seek | Sets the position on the current LOB stream
`SetLength` | Not Supported
`ToString` | Inherited from `Object`
`Write` | Not Supported
`WriteByte` | Not Supported

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Members

## OracleBFile Constructors

`OracleBFile` constructors create new instances of the `OracleBFile` class.

Overload List:

- OracleBFile(OracleConnection)

  This constructor creates an instance of the `OracleBFile` class with an `OracleConnection` object.

- OracleBFile(OracleConnection, string, string)

  This constructor creates an instance of the `OracleBFile` class with an `OracleConnection` object, the location of the `BFILE`, and the name of the `BFILE`.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### OracleBFile(OracleConnection)

This constructor creates an instance of the `OracleBFile` class with an `OracleConnection` object.

Declaration

    // C#
    public OracleBFile(OracleConnection con);

Parameters

- `con`

  The `OracleConnection` object.

Exceptions

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

The connection must be opened explicitly by the application. `OracleBFile` does not open the connection implicitly.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### OracleBFile(OracleConnection, string, string)

This constructor creates an instance of the `OracleBFile` class with an `OracleConnection` object, the location of the `BFILE`, and the name of the `BFILE`.

Declaration

    // C#
    public OracleBFile(OracleConnection con, string directoryName, string
       fileName);

Parameters

- `con`

  The `OracleConnection` object.

- `directoryName`

  The directory alias created by the `CREATE` `DIRECTORY` SQL statement.

- `fileName`

  The name of the external LOB.

Exceptions

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

The `OracleConnection` must be opened explicitly by the application. `OracleBFile` does not open the connection implicitly.

To initialize a `BFILE` column using an `OracleBFile` instance as an input parameter of a SQL `INSERT` statement, `directoryName` and `fileName` must be properly set.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

## OracleBFile Static Fields

`OracleBFile` static fields are listed in Table 10-6.

Table 10-6 OracleBFile Static Fields

Field | Description
--- | ---
MaxSize | The static field holds the maximum number of bytes a `BFILE` can hold, which is 4,294,967,295 (2^32 - 1) bytes

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### MaxSize

This static field holds the maximum number of bytes a `BFILE` can hold, which is 4,294,967,295 (2^32 - 1) bytes.

Declaration

    // C#
    public static readonly Int64 MaxSize = 4294967295;

Remarks

This field is useful in code that checks whether or not the operation exceeds the maximum length allowed.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

## OracleBFile Static Methods

`OracleBFile` static methods are listed in Table 10-7.

Table 10-7 OracleBFile Static Methods

Methods | Description
--- | ---
`Equals` | Inherited from `Object` (Overloaded)

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

## OracleBFile Instance Properties

`OracleBFile` instance properties are listed in Table 10-8.

Table 10-8 OracleBFile Instance Properties

Properties | Description
--- | ---
CanRead | Indicates whether or not the LOB stream can be read
CanSeek | Indicates whether or not forward and backward seek operations can be performed
CanWrite | Indicates whether or not the LOB object supports writing
Connection | Indicates the connection used to read from a `BFILE`
DirectoryName | Indicates the directory alias of the `BFILE`
FileExists | Indicates whether or not the specified `BFILE` exists
FileName | Indicates the name of the `BFILE`
IsEmpty | Indicates whether the `BFILE` is empty or not
IsOpen | Indicates whether the `BFILE` has been opened by this instance or not
Length | Indicates the size of the `BFILE` data in bytes
Position | Indicates the current read position in the LOB stream
Value | Returns the data, starting from the first byte in `BFILE`, as a byte array

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CanRead

Overrides `Stream`

This instance property indicates whether or not the LOB stream can be read.

Declaration

    // C#
    public override bool CanRead{get;}

Property Value

If the LOB stream can be read, returns `true`; otherwise, returns `false`.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CanSeek

Overrides `Stream`

This instance property indicates whether or not forward and backward seek operations can be performed.

Declaration

    // C#
    public override bool CanSeek{get;}

Property Value

If forward and backward seek operations can be performed, returns `true`; otherwise, returns `false`.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CanWrite

Overrides `Stream`

This instance property indicates whether or not the LOB object supports writing.

Declaration

    // C#
    public override bool CanWrite{get;}

Property Value

`BFILE` is read only.

Remarks

`BFILE` is read-only, therefore, the boolean value is always `false`.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Connection

This instance property indicates the connection used to read from a `BFILE`.

Declaration

    // C#
    public OracleConnection Connection {get;}

Property Value

An object of `OracleConnection`.

Exceptions

`ObjectDisposedException` - The object is already disposed.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### DirectoryName

This instance property indicates the directory alias of the `BFILE`.

Declaration

    // C#
    public string DirectoryName {get;set;}

Property Value

A `string`.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The value of the `DirectoryName` changed while the `BFILE` is open.

Remarks

The maximum length of a `DirectoryName` is 30 bytes.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### FileExists

This instance property indicates whether or not the `BFILE` specified by the `DirectoryName` and `FileName` exists.

Declaration

    // C#
    public bool FileExists {get;}

Property Value

`bool`

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

Unless a connection, file name, and directory name are provided, this property is set to `false` by default.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### FileName

This instance property indicates the name of the `BFILE`.

Declaration

    // C#
    public string FileName {get;set}

Property Value

A `string` that contains the `BFILE` name.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The value of the `DirectoryName` changed while the `BFILE` is open.

Remarks

The maximum length of a `FileName` is 255 bytes.

Changing the `FileName` property while the `BFILE` object is opened causes an exception.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### IsEmpty

This instance property indicates whether the `BFILE` is empty or not.

Declaration

    // C#
    public bool IsEmpty {get;}

Property Value

`bool`

Exceptions

`ObjectDisposedException` - The object is already disposed.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### IsOpen

This instance property indicates whether the `BFILE` has been opened by this instance or not.

Declaration

    // C#
    public bool IsOpen {get;}

Property Value

A `bool`.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Length

Overrides `Stream`

This instance property indicates the size of the `BFILE` data in bytes.

Declaration

    // C#
    public override Int64 Length {get;}

Property Value

`Int64`

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Position

Overrides `Stream`

This instance property indicates the current read position in the LOB stream.

Declaration

    // C#
    public override Int64 Position{get; set;}

Property Value

An `Int64` value that indicates the read position.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

`ArgumentOutOfRangeException` - The value is less than 0.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Value

This instance property returns the data, starting from the first byte in `BFILE`, as a byte array.

Declaration

    // C#
    public byte[] Value{get;}

Property Value

A byte array.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

The length of data is bound by the maximum length of the byte array. The current value of the `Position` property is not used or changed.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

## OracleBFile Instance Methods

`OracleBFile` instance methods are listed in Table 10-9.

Table 10-9 OracleBFile Instance Methods

Methods | Description
--- | ---
`BeginRead` | Inherited from `Stream`
`BeginWrite` | Not Supported
Clone | Creates a copy of an `OracleBFile` object
Close | Closes the current stream and releases any resources associated with the stream
CloseFile | Closes the `BFILE` referenced by the current `BFILE` instance
Compare | Compares data referenced by the two `OracleBFile`s
`CreateObjRef` | Inherited from `MarshalByRefObject`
CopyTo | Copies data as specified (Overloaded)
Dispose | Releases resources allocated by this object
`EndRead` | Inherited from `Stream`
`EndWrite` | Not Supported
`Equals` | Inherited from `Object` (Overloaded)
`Flush` | Not Supported
`GetHashCode` | Inherited from `Object`
`GetLifetimeService` | Inherited from `MarshalByRefObject`
`GetType` | Inherited from `Object`
`InitializeLifetimeService` | Inherited from `MarshalByRefObject`
IsEqual | Compares the LOB references
OpenFile | Opens the `BFILE` specified by the `FileName` and `DirectoryName`
Read | Reads a specified amount of bytes from the `OracleBFile` instance and populates the `buffer`
`ReadByte` | Inherited from `Stream`
Search | Searches for a binary pattern in the current instance of an `OracleBFile`
Seek | Sets the position on the current LOB stream
`SetLength` | Not Supported
`ToString` | Inherited from `Object`
`Write` | Not Supported
`WriteByte` | Not Supported

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Clone

This instance method creates a copy of an `OracleBFile` object.

Declaration

    // C#
    public object Clone();

Return Value

An `OracleBFile` object.

Implements

`ICloneable`

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

The cloned object has the same property values as that of the object being cloned.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class CloneSample
    {
      static void Main()
      {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Prints "bFile1.Position = 0"
        Console.WriteLine("bFile1.Position = " + bFile1.Position);

        // Set the Position before calling Clone()
        bFile1.Position = 1;

        // Clone the OracleBFile
        OracleBFile bFile2 = (OracleBFile) bFile1.Clone();

        // Prints "bFile2.Position = 1"
        Console.WriteLine("bFile2.Position = " + bFile2.Position);

        bFile1.Close();
        bFile1.Dispose();

        bFile2.Close();
        bFile2.Dispose();

        con.Close();
        con.Dispose();
      }
    }

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Close

Overrides `Stream`

This instance method closes the current stream and releases any resources associated with it.

Declaration

    // C#
    public override void Close();

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CloseFile

This instance method closes the `BFILE` referenced by the current `BFILE` instance.

Declaration

    // C#
    public void CloseFile();

Remarks

No error is returned if the `BFILE` exists, but is not opened.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Compare

This instance method compares data referenced by the two `OracleBFile`s.

Declaration

    // C#
    public int Compare(Int64 src_offset, OracleBFile obj, Int64 dst_offset,
        Int64 amount);

Parameters

- `src_offset`

  The offset of the current instance.

- `obj`

  The provided `OracleBFile` object.

- `dst_offset`

  The offset of the `OracleBFile` object.

- `amount`

  The number of bytes to compare.

Return Value

Returns a number that is:

- Less than zero: if the `BFILE` data of the current instance is less than that of the provided `BFILE` data.

- Zero: if both the `BFILE`s store the same data.

- Greater than zero: if the `BFILE` data of the current instance is greater than that of the provided `BFILE` data.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

`ArgumentOutOfRangeException` - The `src_offset`, the `dst_offset`, or the `amount` is less than `0`.

Remarks

The provided object and the current instance must be using the same connection, that is, the same `OracleConnection` object.

The `BFILE` needs to be opened using `OpenFile` before the operation.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class CompareSample
    {
      static void Main()
      {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt");
        OracleBFile bFile2 = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Open the OracleBFiles
        bFile1.OpenFile();
        bFile2.OpenFile();

        // Compare 2 bytes from the 1st byte of bFile1 and
        // the 5th byte of bFile2 onwards
        int result = bFile1.Compare(1, bFile2, 5, 2);

        // Prints "result = 0" (Indicates the data is identical)
        Console.WriteLine("result = " + result);

        // Close the OracleBFiles
        bFile1.CloseFile();
        bFile2.CloseFile();

        bFile1.Close();
        bFile1.Dispose();

        bFile2.Close();
        bFile2.Dispose();

        con.Close();
        con.Dispose();
      }
    }

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo

`CopyTo` copies data from the current instance to the provided object.

Overload List:

- CopyTo(OracleBlob)

  This instance method copies data from the current instance to the provided `OracleBlob` object.

- CopyTo(OracleBlob, Int64)

  This instance method copies data from the current `OracleBFile` instance to the provided `OracleBlob` object with the specified destination offset.

- CopyTo(Int64, OracleBlob, Int64, Int64)

  This instance method copies data from the current `OracleBFile` instance to the provided `OracleBlob` object with the specified source offset, destination offset, and character amounts.

- CopyTo(OracleClob)

  This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object.

- CopyTo(OracleClob, Int64)

  This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object with the specified destination offset.

- CopyTo(Int64, OracleClob, Int64, Int64)

  This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object with the specified source offset, destination offset, and amount of characters.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(OracleBlob)

This instance method copies data from the current instance to the provided `OracleBlob` object.

Declaration

    // C#
    public Int64 CopyTo(OracleBlob obj);

Parameters

- `obj`

  The `OracleBlob` object to which the data is copied.

Return Value

The return value is the amount copied.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

The provided object and the current instance must be using the same connection; that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(OracleBlob, Int64)

This instance method copies data from the current `OracleBFile` instance to the provided `OracleBlob` object with the specified destination offset.

Declaration

    // C#
    public Int64 CopyTo(OracleBlob obj, Int64 dst_offset);

Parameters

- `obj`

  The `OracleBlob` object to which the data is copied.

- `dst_offset`

  The offset (in bytes) at which the `OracleBlob` object is copied.

Return Value

The return value is the amount copied.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`ArgumentOutOfRangeException` - The `dst_offset` is less than `0`.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

If the `dst_offset` is beyond the end of the `OracleBlob` data, spaces are written into the `OracleBlob` until the `dst_offset` is met.

The offsets are `0`-based. No character conversion is performed by this operation.

The provided object and the current instance must be using the same connection; that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(Int64, OracleBlob, Int64, Int64)

This instance method copies data from the current `OracleBFile` instance to the provided `OracleBlob` object with the specified source offset, destination offset, and character amounts.

Declaration

    // C#
    public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset,
       Int64 amount);

Parameters

- `src_offset`

  The offset (in bytes) in the current instance, from which the data is read.

- `obj`

  An `OracleBlob` object to which the data is copied.

- `dst_offset`

  The offset (in bytes) to which the `OracleBlob` object is copied.

- `amount`

  The amount of data to be copied.

Return Value

The return value is the amount copied.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`ArgumentOutOfRangeException` - The `src_offset`, the `dst_offset`, or the `amount` is less than `0`.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

If the `dst_offset` is beyond the end of the `OracleBlob` data, spaces are written into the `OracleBlob` until the `dst_offset` is met.

The offsets are `0`-based. No character conversion is performed by this operation.

The provided object and the current instance must be using the same connection; that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(OracleClob)

This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object.

Declaration

    // C#
    public Int64 CopyTo(OracleClob obj);

Parameters

- `obj`

  The `OracleClob` object to which the data is copied.

Return Value

The return value is the amount copied.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

The provided object and the current instance must be using the same connection, that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(OracleClob, Int64)

This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object with the specified destination offset.

Declaration

    // C#
    public Int64 CopyTo(OracleClob obj, Int64 dst_offset);

Parameters

- `obj`

  The `OracleClob` object that the data is copied to.

- `dst_offset`

  The offset (in characters) at which the `OracleClob` object is copied to.

Return Value

The amount copied.

Exceptions

Exceptions

`ObjectDisposedException` - The object is already disposed.

`ArgumentOutOfRangeException` - The `dst_offset` is less than `0`.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

If the `dst_offset` is beyond the end of the `OracleClob` data, spaces are written into the `OracleClob` until the `dst_offset` is met.

The offsets are `0`-based. No character conversion is performed by this operation.

The provided object and the current instance must be using the same connection, that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### CopyTo(Int64, OracleClob, Int64, Int64)

This instance method copies data from the current `OracleBFile` instance to the provided `OracleClob` object with the specified source offset, destination offset, and amount of characters.

Declaration

    // C#
    public Int64 CopyTo(Int64 src_offset,OracleClob obj,Int64 dst_offset,
       Int64 amount);

Parameters

- `src_offset`

  The offset (in characters) in the current instance, from which the data is read.

- `obj`

  An `OracleClob` object that the data is copied to.

- `dst_offset`

  The offset (in characters) at which the `OracleClob` object is copied to.

- `amount`

  The amount of data to be copied.

Return Value

The return value is the amount copied.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`ArgumentOutOfRangeException` - The `src_offset`, the `dst_offset`, or the `amount` is less than `0`.

`InvalidOperationException` - This exception is thrown if any of the following conditions exist:

- The `OracleConnection` is not open or has been closed during the lifetime of the object.

- The LOB object parameter has a different connection than the object.

Remarks

If the `dst_offset` is beyond the end of the current `OracleClob` data, spaces are written into the `OracleClob` until the `dst_offset` is met.

The offsets are `0`-based. No character conversion is performed by this operation.

The provided object and the current instance must be using the same connection, that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Dispose

This instance method releases resources allocated by this object.

Declaration

    // C#
    public void Dispose();

Implements

`IDisposable`

Remarks

Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls may lead to exceptions. The object cannot be reused after being disposed.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### IsEqual

This instance method compares the LOB references.

Declaration

    // C#
    public bool IsEqual(OracleBFile obj);

Parameters

- `obj`

  The provided `OracleBFile` object.

Return Value

Returns `true` if the current `OracleBFile` and the provided `OracleBFile` object refer to the same external LOB. Returns `false` otherwise.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

Note that this method can return `true` even if the two `OracleBFile` objects return `false` for `==` or `Equals()` since two different `OracleBFile` instances can refer to the same external LOB.

The provided object and the current instance must be using the same connection; that is, the same `OracleConnection` object.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### OpenFile

This instance method opens the `BFILE` specified by the `FileName` and `DirectoryName`.

Declaration

    // C#
    public void OpenFile();

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

Many operations, such as `Compare()`, `CopyTo()`, `Read()`, and `Search()` require that the `BFILE` be opened using `OpenFile` before the operation.

Calling `OpenFile` on an opened `BFILE` is not operational.

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Read

Overrides `Stream`

This instance method reads a specified amount of bytes from the `OracleBFile` instance and populates the `buffer`.

Declaration

    // C#
    public override int Read(byte[ ] buffer, int offset, int count);

Parameters

- `buffer`

  The byte array buffer to be populated.

- `offset`

  The offset of the byte array buffer to be populated.

- `count`

  The amount of bytes to read.

Return Value

The return value indicates the number of bytes read from the `BFILE`, that is, the external LOB.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

`ArgumentOutOfRangeException` - Either the `offset` or the `count` parameter is less than `0` or the `offset` is greater than or equal to the `buffer`.`Length` or the `offset` and the `count` together are greater than `buffer`.`Length`.

Remarks

The LOB data is read starting from the position specified by the `Position` property.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class ReadSample
    {
      static void Main()
      {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Open the OracleBFile
        bFile.OpenFile();

        // Read 7 bytes into readBuffer, starting at buffer offset 0
        byte[] readBuffer = new byte[7];
        int bytesRead = bFile.Read(readBuffer, 0, 7);

        // Prints "bytesRead  = 7"
        Console.WriteLine("bytesRead  = " + bytesRead);

        // Prints "readBuffer = 65666768656667"
        Console.Write("readBuffer = ");
        for(int index = 0; index <  readBuffer.Length; index++)
        {
          Console.Write(readBuffer[index]);
        }
        Console.WriteLine();

        // Close the OracleBFile
        bFile.CloseFile();

        bFile.Close();
        bFile.Dispose();

        con.Close();
        con.Dispose();
      }
    }

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Search

This instance method searches for a binary pattern in the current instance of an `OracleBFile`.

Declaration

    // C#
    public int Search(byte[ ] val, Int64 offset, Int64 nth);

Parameters

- `val`

  The binary pattern being searched for.

- `offset`

  The `0`-based offset (in bytes) starting from which the `OracleBFile` is searched.

- `nth`

  The specific occurrence (`1`-based) of the match for which the offset is returned.

Return Value

Returns the absolute `offset` of the start of the matched pattern (in bytes) for the `nth` occurrence of the match. Otherwise, `0` is returned.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

`ArgumentOutOfRangeException` - Either the `offset` is less than `0` or `nth` is less than or equal to `0` or `val`.`Length` is greater than `16383` or `nth` is greater than or equal to `OracleBFile.MaxSize` or `offset` is greater than or equal to `OracleBFile.MaxSize`.

Remarks

The limit of the search pattern is 16383 bytes.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class SearchSample
    {
      static void Main()
      {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Open the OracleBFile
        bFile.OpenFile();

        // Search for the 2nd occurrence of a byte pattern {66,67}
        // starting from byte offset 1 in the OracleBFile
        byte[] pattern = new byte[2] {66, 67};
        long posFound = bFile.Search(pattern, 1, 2);

        // Prints "posFound = 6"
        Console.WriteLine("posFound = " + posFound);

        // Close the OracleBFile
        bFile.CloseFile();

        bFile.Close();
        bFile.Dispose();

        con.Close();
        con.Dispose();
      }
    }

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members

### Seek

Overrides `Stream`

This instance method sets the position on the current LOB stream.

Declaration

    // C#
    public override Int64 Seek(Int64 offset, SeekOrigin origin);

Parameters

- `offset`

  A byte offset relative to origin.

- `origin`

  A value of type `System.IO.SeekOrigin` indicating the reference point used to obtain the new position.

Return Value

Returns an `Int64` that indicates the position.

Exceptions

`ObjectDisposedException` - The object is already disposed.

`InvalidOperationException` - The `OracleConnection` is not open or has been closed during the lifetime of the object.

Remarks

If `offset` is negative, the new position precedes the position specified by `origin` by the number of bytes specified by `offset`.

If `offset` is zero, the new position is the position specified by `origin`.

If `offset` is positive, the new position follows the position specified by `origin` by the number of bytes specified by `offset`.

`SeekOrigin.Begin` specifies the beginning of a stream.

`SeekOrigin.Current` specifies the current position within a stream.

`SeekOrigin.End` specifies the end of a stream.

Example

    // Database Setup, if you have not done so yet.
    /* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.

    CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';

    */

    // C#

    using System;
    using System.IO;
    using Oracle.DataAccess.Client;
    using Oracle.DataAccess.Types;

    class SeekSample
    {
      static void Main()
      {
        // Create MYDIR directory object as indicated previously and create a file
        // MyFile.txt with the text ABCDABC under C:\TEMP directory.
        // Note that the byte representation of the ABCDABC is 65666768656667

        string constr = "User Id=scott;Password=tiger;Data Source=oracle";
        OracleConnection con = new OracleConnection(constr);
        con.Open();

        OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");

        // Open the OracleBFile
        bFile.OpenFile();

        // Set the Position to 2 with respect to SeekOrigin.Begin
        long newPosition = bFile.Seek(2, SeekOrigin.Begin);

        // Prints "newPosition     = 2"
        Console.WriteLine("newPosition     = " + newPosition);

        // Prints "bFile.Position  = 2"
        Console.WriteLine("bFile.Position  = " + bFile.Position);

        // Read 2 bytes into readBuffer, starting at buffer offset 1
        byte[] readBuffer = new byte[4];
        int bytesRead = bFile.Read(readBuffer, 1, 2);

        // Prints "bytesRead       = 2"
        Console.WriteLine("bytesRead       = " + bytesRead);

        // Prints "readBuffer      = 067680"
        Console.Write("readBuffer      = ");
        for(int index = 0; index <  readBuffer.Length; index++)
        {
          Console.Write(readBuffer[index]);
        }
        Console.WriteLine();

        // Close the OracleBFile
        bFile.CloseFile();

        bFile.Close();
        bFile.Dispose();

        con.Close();
        con.Dispose();
      }
    }

See Also: "Oracle.DataAccess.Types Namespace" OracleBFile Class OracleBFile Members